/*
 * Copyright 2011 Digia Oyj - Pasi Hirvonen <pasi.hirvonen@digia.fi>
 *
 * XmlRpcConnection represents a connection to a XML-RPC server.
 *
 * It holds the connection details for the remote server as well
 * as any possible authentication data. XmlRpcRequests are
 * sent to the remote server using the connection's query()
 * call.
 */

#ifndef TRACRPCCONNECTION_H
#define TRACRPCCONNECTION_H

#include <QtCore/QObject>

class QUrl;

namespace XmlRpc {

class XmlRpcResponse;
class XmlRpcRequest;

class XmlRpcConnectionPrivate;

class XmlRpcConnection : public QObject
{
    Q_OBJECT
public:
    explicit XmlRpcConnection(QObject *parent = 0);
    virtual ~XmlRpcConnection();

    /*
     * The username and password are used for basic HTTP authentication.
     * Setting the username and password here is no different from setting
     * them in the QUrl before calling setUrl(). These calls will override
     * whatever was set in the QUrl previously.
     *
     * Furthermore, requests marked 'anonymous' are always executed without
     * the username-password combination, even if one is set.
     */
    void setUsername(const QString &username);
    void setPassword(const QString &password);

    /* Set the XML-RPC remote end URL. */
    void setUrl(const QUrl &url);
    QUrl url() const;

    /* Sends an XmlRpcRequest to the remote XML-RPC server asynchronously. */
    XmlRpcResponse *query(const XmlRpcRequest &request);
    /* Same as query(), but synchronous. After execute() finishes, the response has
     * either finished or timeout_msecs have elapsed. No special indication of timeout
     * is given. Users of execute() must use isFinished() etc to see if timeout occurred.
     * Note that XmlRpcRequest::DoPropagate is ignored for synchronous requests. */
    XmlRpcResponse *execute(const XmlRpcRequest &request, quint32 timeout_msecs = 3000);

signals:
    /* Normally emitted when a response is received. See XmlRpcRequest
     * class' Propagate enum. */
    void finished(XmlRpc::XmlRpcResponse *response);

public slots:

private:
    friend class XmlRpcConnectionPrivate;
    XmlRpcConnectionPrivate *d;
    Q_DISABLE_COPY(XmlRpcConnection)
};

} // namespace XmlRpc

#endif // TRACRPCCONNECTION_H
